ContentConnect

Content assets which are created in FirstSpirit get a unique ID from FirstSpirit. If a content asset with the exact same ID is created in Commerce Cloud, this is overwritten by FirstSpirit when it is deployed.

The ContentConnect delivery contains three modules that are added on the FirstSpirit Server. To install the modules, open the ServerManager and select Server properties → Modules.

Figure 3. Module management in the server properties

The main panel contains a list of all the modules installed on the FirstSpirit Server. Click Install, then select the contentconnect-fsm-<version number>.fsm file provided first, followed by the WebDavDeployment-<version number>.fsm and jstl.fsm files. Each time you make a selection, click Open to confirm it. Once installation has been successfully completed, the folders ContentConnect, WebDavDeployment, and JSTL are added to the list. Each of these must be given All permissions.

The process of installing the modules must be completed by adding the Apache Commons Codec, version 1.8. This is a library that the WebDAV module uses.

For this purpose you require the commons-codec-1.8-bin.zip archive, which you can download from the following URL: http://commons.apache.org/proper/commons-codec

Extract the file anywhere within your file system and separate the commons-codec-1.8.jar file. This jar file must be added to the FirstSpirit Server: To do this, open the directory for your FirstSpirit installation, switch to the shared → lib sub-folder and copy the jar file to this location.

To use the WebDAV server with https instead of http, it is not generally necessary to perform any additional configuration work. However, a local certificate authority managed by the company is normally used for https. The certificate in question, including the entire chain up to the certificate on the WebDAV server, must be made available to the FirstSpirit Server's JVM.

Using the command below, import the public root or intermediate certificates into a JKS file and select Yes in answer to the question whether the certificate is to be trusted. You must repeat this process for each certificate.

keytool -import -file cert1.crt -keystore truststore.jks -storepass changeit

Copy the Trust Store that is generated into the firstspirit5 → conf directory of your FirstSpirit Server and add the following lines to the file firstspirit5 → conf → fs-wrapper.conf.

wrapper.java.additional.100=-Djavax.net.ssl.trustStore=conf/truststore.jks
wrapper.java.additional.101=-Djavax.net.ssl.trustStorePassword=changeit
wrapper.java.additional.102=-Djavax.net.ssl.trustStoreType=JKS

If the WebDAV server is expecting mutual SSL authentication, you must use the following calls to create and sign a client certificate as a first step.

openssl genrsa -out private.key 2048
openssl req -new -key private.key -out request.csr

The file request.csr is sent to the certificate authority, which responds with the file cert.crt. The private key, the public certificate, and the certificate from the certificate authority must then be collected in a Key Store to be read by the JVM.

cd firstspirit5/conf
openssl pkcs12 -export -in public.crt -inkey private.key \
-out clientcert.p12 -CAfile authority.crt

If the certificate chain consists of one or more intermediate certificates, you can import them via keytool.

keytool -import -file intermediate1.crt -trustcacerts \
-keystore clientcert.p12 -storepass changeit

The Key Store can be transferred to the JVM of the FirstSpirit Server by adding the following lines to firstspirit5 → conf → fs-wrapper.conf.

wrapper.java.additional.103=-Djavax.net.ssl.keyStore=conf/clientcert.p12
wrapper.java.additional.104=-Djavax.net.ssl.keyStorePassword=changeit
wrapper.java.additional.105=-Djavax.net.ssl.keyStoreType=PKCS12

A project-specific configuration is required in order to use the ContentConnect module. It is set up using the project component, which must be added to the project being used. To add the project component, open the ServerManager and select Project properties → Project components.

Figure 4. Project components in the project properties

A list of all existing project components is displayed in the main panel. Click Add, then select the ContentConnect Project Configuration and click OK to confirm your selection. The project component is then added to the list in the main panel and will need to be configured (see figure Project components in the project properties). To configure the project component, select the entry in the list and click Configure to open the associated dialog (see figure Configuration dialog for the project component).

Figure 5. Configuration dialog for the project component

<CMS_INPUT_TEXT name="dw_item_id" hidden="yes" useLanguages="no">
  <LANGINFOS>
    <LANGINFO lang="*" label=""/>
  </LANGINFOS>
</CMS_INPUT_TEXT>

Figure 6. Category report

As some templates contain JSTL code, you must switch the template set presentation channel setting from html to JSP before the import. Otherwise, the presentation channels for the imported templates will be empty. Additionally, the conversion rule being used must contain the following line: "0x24="$". If it does not, you can add the line via ServerManager → Server properties → Conversion rules. Figure 7. html template set

Two web components need to be added for the preview and for ContentCreator. To add a web component, open the ServerManager and select Project properties → Web components.

Figure 8. Web components in the project properties

Inside the main panel, various tabs are visible. Each tab contains a list of the existing web components. For the first tab page selected (Preview), click Add, select the ContentConnect Web Resources and FS_JSTL_WebApp, and click OK to confirm.

Repeat this process for ContentCreator. The web components for each of the two tab pages are then added to the list in the main panel (see figure Web components in the project properties).

The web components must be installed on an active web server and then activated. The server can be selected using the selection box.

More detailed information on how to add web components is available in the FirstSpirit Documentation for Administrators.

Some project-specific information is required for the ContentConnect module functions. This is specified in the project settings.

The template must be selected in the project properties and has to exist in the project for this purpose. If the template does not exist, start by creating it. If the template already exists, open the ServerManager and switch to Project properties → Options. Then click the corresponding button to select the project settings (see figure Options in the project properties). Clicking the OK button saves any changes that have been made.

Figure 9. Options in the project properties

The delivery includes the int_firstspirit_cms cartridge, which must be transferred to Commerce Cloud initially. Different methods for this are described in the Commerce Cloud documentation under Developing your storefront → Development components → Cartridges.

Next, the cartridge must be added to all sites which are to receive FirstSpirit content, as well as the business manager site. You can find relevant instructions in the Commerce Cloud documentation under Getting started → Getting started for developers → Registering your cartridge.

To import the content and slot configurations generated by FirstSpirit into Commerce Cloud, a job schedule must be created in Commerce Cloud for each site. To do this, the cartridge defines two job steps:

Both have the mandatory parameters Import File and Import Mode:

The job schedule should contain a workflow with two parallel flows. Each flow can then call one of the two job steps above.

In addition to the cartridge, in the metadata directory, the delivery also contains an export file for a job schedule, which can be used for reference purposes and which makes it easier to create the different job schedules.

After the import, further adaptations need to be made to the job schedule. The scope of both job flows must be set to the correct site. The Import File parameter must also be adapted in both job steps so that it contains the correct path.

There is only one difference between the two methods of referencing Commerce Cloud products, as mentioned in the previous chapter. This chapter will therefore focus on providing an outline of how to implement the FS_LIST; it will only refer to the difference in relation to the link template at the appropriate point.

The FS_LIST is defined in the sample project within the Featured Products section template, whose form also includes the clickHandler and dropHandler buttons. Both of these buttons use the class Demandware_ProductDropHandler, which is part of the ContentConnect module and controls Commerce Cloud product transfer.

<FS_LIST name="st_productList" hFill="yes" height="400">
   <DATASOURCE type="inline" useLanguages="yes">
      <LABELS>
         <LABEL lang="*">#item.name</LABEL>
      </LABELS>
      [...]
      <TEMPLATES source="linktemplates">
         <TEMPLATE uid="list_product_link"/>
      </TEMPLATES>
   </DATASOURCE>
</FS_LIST>

<FS_BUTTON
    name="dropHandler"
    icon="media:drop_zone_product"
    noBreak="yes"
    onDrop="class:DemandwareConnect_ProductDropHandler"
    style="link">

   <DROPTYPES>
        <MIME type="application/x-java-serialized-object"
            classname="com.espirit.moddev.demandware.products.Product"/>
   </DROPTYPES>
   <PARAMS>
      <PARAM name="list">#field.st_productList</PARAM>
      <PARAM name="id">id</PARAM>
      <PARAM name="name">name</PARAM>
   </PARAMS>
</FS_BUTTON>

<FS_BUTTON name="clickHandler" onClick="class:DemandwareConnect_ProductDropHandler">
   <LANGINFOS>
      <LANGINFO lang="*" label="Add product from selection"/>
   </LANGINFOS>
   <PARAMS>
      <PARAM name="list">#field.st_productList</PARAM>
      <PARAM name="id">id</PARAM>
      <PARAM name="name">name</PARAM>
   </PARAMS>
</FS_BUTTON>

The two buttons are also used in the Product Hot Spot link template. However, the parameters for the buttons must be defined differently in this case:

<PARAMS>
   <PARAM name="id">#field.id</PARAM>
   <PARAM name="name">#field.name</PARAM>
   <PARAM name="variationAttributes">#field.variationAttributes</PARAM>
</PARAMS>

The reason for this difference is that the id and name fields in the link template form are positioned in parallel to the two buttons, and are therefore addressed directly by the #field prefix expression. In the Featured Products section template, on the other hand, the buttons are arranged in parallel to the FS_LIST and the id and name fields are located in the list_product_link link template that is referenced by the FS_LIST.

The two buttons in the link template form also have the variationAttributes parameter, which addresses a hidden text field. This field is used for the persistence of specific variation attributes associated with a product. As the Featured Products section template is only used for outputting general product information, the buttons in its form do not require this parameter.

These buttons allow editors to create Commerce Cloud product referencing quickly and easily in FirstSpirit without having to leave the Client. Otherwise, they would need to determine the product information in Commerce Cloud and then enter it manually. Each FirstSpirit Client only ever shows one of the two buttons.

Figure 13. dropHandler

Figure 14. clickHandler

As mentioned previously, each of the two FirstSpirit Clients only shows one specific button. This means that whichever button is shown in each case has to be hidden in the other Client. This requirement is controlled by rules that are defined in the specified section template and in the link template.

The first query activates the clickHandler button when a Commerce Cloud product shown in the report has been copied to the clipboard.
The last two queries check whether the current editor is in ContentCreator. If the editor is in SiteArchitect, the clickHandler button is shown. Otherwise, the dropHandler button appears.

<RULES>
   <ON_EVENT>
      <SCHEDULE service="DemandwareConnect_ClipboardFilled" id="product_link_clipboard_check">
         <!-- Some FS versions complain about an invalid rule definition without a parameter -->
         <PARAM name="dummy">
            <TEXT>dummy</TEXT>
         </PARAM>
      </SCHEDULE>
      <DO>
         <PROPERTY source="clickHandler" name="EDITABLE" />
      </DO>
   </ON_EVENT>

   <ON_EVENT>
      <WITH>
         <NOT>
            <PROPERTY source="#global" name="WEB"/>
         </NOT>
      </WITH>
      <DO>
         <PROPERTY source="clickHandler" name="VISIBLE"/>
      </DO>
   </ON_EVENT>

   <ON_EVENT>
      <WITH>
         <PROPERTY source="#global" name="WEB"/>
      </WITH>
      <DO>
         <PROPERTY source="dropHandler" name="VISIBLE"/>
      </DO>
   </ON_EVENT>
</RULES>

If the variationAttributes text field appears in the form for the template that is being used, an additional dialog opens when a master product is referenced using one of the two buttons. This dialog shows all the variation attributes associated with the selected product; these attributes can be used to specify the product selection (see figure Product specification).

If the specification defines a certain product variant, the information relating to this variant is stored in the id and name fields of the link template or the FS_LIST. Otherwise, the ID and the name of the master product are accepted, and the variation attributes defined in the dialog are persisted in the form of a JSON in the hidden variationAttributes field.

Figure 15. Product specification

The Product Manager can be used to query other product information for the purpose of displaying referenced products in the preview. The Product Manager is initialized in the project settings whose template was imported into the project during the process of configuring the project component. Depending on the application, the Product Manager can be used to determine both specific variation attributes and general product information.

This chapter outlines the concept of a "general products" list. In this case, only general information such as the name and price of a product is required. Specific attributes, by contrast, do not matter in this case.

The example below is based on the assumption that the FS_LIST described above has been used for referencing products. It is possible to reproduce this example using the Featured Products section template.

Each product that is referenced in the FS_LIST is first loaded by the Product Manager when the FOR loop is run. If the editor is in the preview, the product image, name, and price are then determined and are shown using simple getter methods.

$CMS_FOR(for_product,st_productList)$
   $CMS_IF(!for_product.id.isEmpty)$
      $CMS_SET(set_product,ps_productManager.loadProduct(for_product.id))$
      [...]
      $CMS_IF(!#global.preview)$
         [...]
      $CMS_ELSE$
         $-- FirstSpirit Preview --$
         <li>
            <div class="product-tile">
               <div class="product-image">
                  <a class="thumb-link" href="#" title="">
                     <img src="$CMS_VALUE(set_product.getImageUrl(set_width,set_height))$">
                  </a>
               </div>
               <div class="product-name">
                  <a class="name-link" href="#">
                     $CMS_VALUE(set_product.getName())$
                  </a>
                  <div class="product-price">
                     <span class="price-sales">
                        $CMS_VALUE(set_product.getCurrency())$
                        $CMS_VALUE(set_product.getPrice().format("0.00"))$
                     </span>
                  </div>
               </div>
               [...]
            </div>
         </li>
      $CMS_END_IF$
   $CMS_END_IF$
$CMS_END_FOR$

In contrast to the general data display described in the previous chapter, the Product Manager can be used to query even specific product information.

This chapter outlines the concept of "Hot Spots". Hot Spots are links to specific product variants. They require the variation attributes that are associated with the variant in question. General information, by contrast, does not matter in this case.

The example below is based on the assumption that the Product Hot Spot link template described above has been used for referencing a product. It is possible to reproduce the example using the template.

In the case of a product that is referenced using the link template, a link to the LinkProduct Commerce Cloud pipeline is generated first and the product ID is then transferred to the link. If the case already concerns a specific variant, the variationAttributes field remains empty. Otherwise, the Product Manager loads all the variation attributes that have been defined for product referencing purposes and are stored in the field. The Product Manager loads them one after another. The ID of each attribute (such as "Color") and its selected value (such as "yellow") are determined, and this information is used to generate a list separated by "&" characters. Finally, this list is added onto the link to the Commerce Cloud LinkProduct pipeline that was initially generated.

$CMS_IF(!#global.preview)$
   $CMS_SET(set_lt_link,"$link-product:pid="+id+"$&")$

   $CMS_IF(!variationAttributes.isEmpty)$
      $CMS_SET(set_attributes, ps_productManager.convertVariationValuesJSON2List(variationAttributes).map(x -> x.key + "=" + x.value).toString("&"))
      $CMS_SET(set_lt_link, set_lt_link + set_attributes)$
   $CMS_END_IF$
$CMS_END_IF$

<a href="$CMS_VALUE(set_lt_link)$"> ... </a>

Objects for which a detail page does not yet exist are identified in the report by a gray icon (see figure Creating a detail page). If a page template has been defined in the project component, the button is displayed when you hover over them.

Figure 16. Creating a detail page

Click on this button to open a dialog that is split into two sections and in which a detail page can be created for the corresponding object.

The top section of the dialog is the structure selection area; it is completed automatically and as such is always the same. Within the structure, the editor has the option to select the menu level at which to generate the new detail page. The corresponding input component may already have been preassigned. In this case, a structure folder will already have been defined in the configuration dialog of the project component. However, the editor is free to change this selection.

Unlike the structure selection area, the form area underneath is always project-specific. It shows the form for the page template specified in the project component. The rules defined in the template also apply here.

An example dialog is shown in the figure below:

Figure 17. Dialog for creating a detail page

Click on Create to generate the page reference for the detail page at the selected menu level. The corresponding page is created in a specific folder in the Page Store.

If a script has been specified in the project component, it is executed before and after the detail page is created.

The following parameters are transferred to this script:

Once the process to generate the detail page and the execution of the script have been completed, the new page is called up.

Objects for which a detail page already exists are identified in the report by a green icon (see figure Product with detail page). When you hover over them, the button is displayed. Click this button to call up the corresponding detail page.

Figure 18. Product with detail page

Objects which have a detail page but its page reference or underlying page cannot be found are identified in the report by a red icon (see figure Broken object). When you hover over them, the button is displayed. Click on this button to open a dialog containing more information.

Figure 19. Broken object

The task of the JavaScript controller is to read out a transferred content asset and display it using a Velocity page template. This task can be divided into four basic steps:

The information below describes these steps and how they are implemented.

The JavaScript controller contains a public Show method that serves as the access point for rendering content assets and uses the dw.template.Velocity and dw.content.ContentMgr classes from the Commerce Cloud Script API. Therefore, the basic framework of the controller is as follows:

"use strict";

var contentManager = require("dw/content/ContentMgr"); ❶
var velocity = require('dw/template/Velocity'); ❷

exports.Show = function() { ❸
    // ...
};

exports.Show.public = true; ❹

The process of reading out the content asset starts by determining the HTTP GET parameter cid, whose value is then transferred to ContentMgr in order to read out the content asset. If an editor creates a new page, Commerce Cloud is not yet aware of a content asset corresponding to it. To enable a preview of the new page to be created in FirstSpirit despite this, a temporary object that imitates an empty asset is used instead of the content asset in this case.

var contentAssetId = request.getHttpParameterMap().get("cid"); ❶
var contentAsset = contentManager.getContent(contentAssetId) ❷
                || { custom: { body: "" }, template: "welcome_page.vs" }; ❸

An object with the name global is then defined. This object is used to provide the Velocity engine with a specialized API whose functions and properties can be used in the Velocity page template being processed. The structure and content of this object must be defined and implemented on a project-specific and page-specific basis. For example, this may involve functions that integrate various widgets under a descriptive name.

var global = {
    ❶
};

The body property stores the content of the content asset. In the approach described here, it must always be present in the global object, in any form. As the asset content may itself contain Velocity code, it is first interpreted using the Velocity engine and the result is stored in body. When the content asset is rendered, the Velocity engine may be provided with a separate parameter object. However, it is possible to reuse global in exactly the same way.

function render(content, parameters) {
    var writer = new dw.io.StringWriter();
    velocity.render(content, parameters, writer)
    return writer.toString();
}

// ...

global.body = render(contentAsset.custom.body, global);

Finally, the Velocity page template stored for the content asset is rendered and the result is displayed for the caller. The global object that was created previously is transferred as a parameter object.

velocity.renderTemplate(contentAsset.template, global);

Commerce Cloud offers several options for caching pages, ensuring rapid response times as a result. If, however, a page contains customer-specific or session-specific information and caching has not been configured correctly, this may quickly lead to unexpected results.

Building on the explanations in chapter JavaScript controller, the information below uses a concrete example to outline an approach that ensures an accurate result.

A page consisting of four blocks must be displayed. These blocks are made up of

These blocks offer different potential for caching.

The banner is only dependent on the customer's gender. This means that all customers can be divided into two groups: male and female. The content is identical for all customers within a group, but customers in different groups see different content. For this reason, the content can be separated for the two groups and cached over a more extensive period. Each time a page is called up, however, the customer's gender must be evaluated in order to address the correct cache.

The header contains information that is specific to each individual customer, such as his or her name. This component therefore requires caching to take place on a customer-by-customer basis. A short validity period may be maintained for the cache, as customer-specific content is required less often and for a shorter time as compared with general content.

The footer is not personalized and may, therefore, be cached for all customers and for an extended period.

The content of the content asset may itself contain Velocity code, which is why it must be viewed on a differentiated basis. However, the same information applies to it, which is why it will not be addressed in any more detail here.

The individual components have different caching requirements. It therefore makes sense to encapsulate each in a separate widget so that caching can be controlled for each one individually. As Commerce Cloud caching is based on URLs and parameters are transferred to a widget via its request URL, widget caching may be controlled via parameters. For example, it may make sense to use an isFemale parameter - containing a Boolean value - for the banner widget. This will result in two potentially valid URLs, in turn leading to two caches for the widget: one for female customers and one for male customers. An id parameter, containing the customer ID, may be defined for the header widget in exactly the same way. As a result, the content that is specific to each customer is maintained on an individual basis.

The individual widgets are then integrated by means of remote includes when the page that was initially called up is rendered. There is also the option of caching the complete result of this page; however, doing so would eliminate the settings for the individual widgets and lead to unexpected results. It is therefore important to avoid caching this response. Consequently, the requested page is reassembled each time a call is made, but the individual components are reused by means of their individual caching.

This is implemented via the JavaScript controller and the global parameter object, which the controller provides to the Velocity engine. In this example, the global object contains the parameter-free functions include.banner(), include.header(), and include.footer(), which are called up at the appropriate points in the Velocity page template. As before, it also contains the body property, which stores the content of the content asset. Within the include functions, each of the widgets is integrated into the page by means of Velocity.remoteInclude calls with appropriate parameters. The JavaScript controller which was initially called up, and which generates the global object and triggers Velocity page template rendering, must not be cached (as mentioned) in order to ensure that it is executed upon each page call and does not bypass the caching settings of the individual widgets. This is the default behavior, which is why no additional code is required.

Figure Example of caching shows the relationship between the Velocity page template, the parameter object, and widgets.

Figure 27. Example of caching

The Velocity page template that is used is maintained in FirstSpirit and transferred to Commerce Cloud. A page template whose presentation channel has the following content in this example must be created in FirstSpirit as a starting point:

<!DOCTYPE html>
<html>
    <body>
        <!-- CMS-PREVIEW-CONTENT-START --> ❶
        $body ❷
        <!-- CMS-PREVIEW-CONTENT-END --> ❸
    </body>
</html>

Exactly one page and one page reference in each case must then be created on the basis of this new page template. The page reference at the very least should be placed on the top level of the structure in a separate folder, in order to simplify the subsequent process of transferring the Velocity page template to Commerce Cloud.

FirstSpirit generates the Velocity page template once the objects created in chapter Velocity page template have been released. For the purposes of transfer to Commerce Cloud, the schedule described in chapter Deployment schedule must be extended to include an additional WebDAV deployment. The easiest way to do this is to generate and adapt a copy of the action from chapter WebDAV deployment. The following parameters must be edited:

All other parameters can be accepted.

As this approach of using the Content Integration API continues to generate content assets, all the information in chapter Page template applies to page templates for editorial content. It is only necessary to make two specific amendments.

Firstly, it is necessary to maintain the template attribute for the content asset, as this is used in the JavaScript controller to determine the correct Velocity page template.

Additionally, a new page type must be defined for all new page templates in order to ensure that the URL generated for the preview contains the correct JavaScript controller call. Specifically, the pt_dwre_previewType must therefore be set to a new value. For the purposes of the example in this chapter, content is used.

The format template included in the delivery, Create Preview URL, needs to be extended to include one additional case so that the preview of pages which use the Content Integration API will work correctly.

The comparison value depends on the new page type that was used in the page template from chapter Page template for editorial content.

Accordingly, the called-up URL depends on the name of the controller, the method to be called, and the parameters that are required (see chapter JavaScript controller).

Therefore, in this example the new entry in the Create Preview URL template would be:

$CMS_CASE("content")$Content-Show?cid=$CMS_VALUE(pageId)$

Earlier on, it was stated that the Content Integration API offers editors more options when designing a page. In Commerce Cloud, widgets are the most ideal way of implementing visual components in cases where an editor needs to be able to place and arrange these on a page. In FirstSpirit, it is then possible to define a section template for each widget.

It is necessary to distinguish between what is a preview and what is not a preview in the presentation channel of this kind of template. The request URL of the widget is determined so that it can be used for the preview. This URL is then transferred to the include_html script, which is part of the delivery. The URL is called up in this script and the result is inserted in the generated page.

Where generating the content asset is concerned, only a Velocity call is generated. Which function is called up and which parameters it expects depends on the parameter object, which is defined in the JavaScript controller and is transferred to the Velocity engine when the content asset is rendered.

The Presentation channel for a widget section template listing contains a generalized example. A general function, which adopts the name of the widget and the required parameters, is used for embedding the widget.

Presentation channel for a widget section template. 

$CMS_IF(#global.isPreview)$
    <div $CMS_VALUE(editorId())$ >
        $CMS_SET(set_includeURL, ps_dwProtocol + ps_dwInstance + ".demandware.net/on/demandware.store/")$
        $CMS_SET(set_includeURL, set_includeURL + "Sites-" + ps_dwSiteId + "-Site/")$
        $CMS_SET(set_includeURL, set_includeURL + #global.language.abbreviation + "/")$ ❶
        $CMS_SET(set_includeURL, set_includeURL + <ACTION> + <PARAMETER>)$

        $CMS_RENDER(script:"include_html", includeURL:set_includeURL.toString())$
    </div>
$CMS_ELSE$
    $include.widget("<ACTION>", <PARAMETER>)
$CMS_END_IF$